<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Task management API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'tasks.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/tasks.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/tasks.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/tasks.html" rel="nofollow" target="_blank">../en/tasks.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="cluster.html">Cluster APIs</a></span>
»
<span class="breadcrumb-node">Task management API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="cluster-remote-info.html">« Remote cluster info API</a>
</span>
<span class="next">
<a href="voting-config-exclusions.html">Voting configuration exclusions API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="tasks"></a>Task management API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h2>
</div></div></div>

<div class="warning admon">
<div class="icon"></div>
<div class="admon_content">
<p>The task management API is new and should still be considered a beta feature. The API may change in ways that are not backwards compatible. For feature status, see <a href="https://github.com/elastic/elasticsearch/issues/51628" class="ulink" target="_top">#51628</a>.</p>
</div>
</div>
<p>Returns information about the tasks currently executing in the cluster.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="tasks-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">GET /_tasks/&lt;task_id&gt;</code></p>
<p><code class="literal">GET /_tasks</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="tasks-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The task management API returns information
about tasks currently executing
on one or more nodes in the cluster.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="tasks-api-path-params"></a>Path parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">&lt;task_id&gt;</code>
</span>
</dt>
<dd>
(Optional, string) ID of the task to return
(<code class="literal">node_id:task_number</code>).
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="tasks-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">actions</code>
</span>
</dt>
<dd>
<p>(Optional, string)
Comma-separated list or wildcard expression
of actions used to limit the request.</p>
<p>Omit this parameter to return all actions.</p>
</dd>
<dt>
<span class="term">
<code class="literal">detailed</code>
</span>
</dt>
<dd>
(Optional, boolean)
If <code class="literal">true</code>,
the response includes detailed information about shard recoveries.
Defaults to <code class="literal">false</code>.
</dd>
<dt>
<span class="term">
<code class="literal">group_by</code>
</span>
</dt>
<dd>
<p>(Optional, string)
Key used to group tasks in the response.</p>
<p>Possible values are:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">nodes</code>
</span>
</dt>
<dd>
(Default)
Node ID
</dd>
<dt>
<span class="term">
<code class="literal">parents</code>
</span>
</dt>
<dd>
Parent task ID
</dd>
<dt>
<span class="term">
<code class="literal">none</code>
</span>
</dt>
<dd>
Do not group tasks.
</dd>
</dl>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">node_id</code>
</span>
</dt>
<dd>
(Optional, string)
Comma-separated list of node IDs or names
used to limit returned information.
</dd>
<dt>
<span class="term">
<code class="literal">parent_task_id</code>
</span>
</dt>
<dd>
<p>(Optional, string)
Parent task ID
used to limit returned information.</p>
<p>To return all tasks,
omit this parameter
or use a value of <code class="literal">-1</code>.</p>
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">wait_for_completion</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, the request blocks until the operation is complete.
Defaults to <code class="literal">true</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="tasks-api-response-codes"></a>Response codes<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">404</code> (Missing resources)
</span>
</dt>
<dd>
If <code class="literal">&lt;task_id&gt;</code> is specified but not found, this code indicates that there
are no resources that match the request.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="tasks-api-examples"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks <a id="CO551-1"></a><i class="conum" data-value="1"></i>
GET _tasks?nodes=nodeId1,nodeId2 <a id="CO551-2"></a><i class="conum" data-value="2"></i>
GET _tasks?nodes=nodeId1,nodeId2&amp;actions=cluster:* <a id="CO551-3"></a><i class="conum" data-value="3"></i></pre>
</div>
<div class="console_widget" data-snippet="snippets/1414.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO551-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Retrieves all tasks currently running on all nodes in the cluster.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO551-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Retrieves all tasks running on nodes <code class="literal">nodeId1</code> and <code class="literal">nodeId2</code>.  See <a class="xref" href="cluster.html#cluster-nodes" title="Node specification">Node specification</a> for more info about how to select individual nodes.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO551-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>Retrieves all cluster-related tasks running on nodes <code class="literal">nodeId1</code> and <code class="literal">nodeId2</code>.</p>
</td>
</tr>
</table>
</div>
<p>The API returns the following result:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "nodes" : {
    "oTUltX4IQMOUUVeiohTt8A" : {
      "name" : "H5dfFeA",
      "transport_address" : "127.0.0.1:9300",
      "host" : "127.0.0.1",
      "ip" : "127.0.0.1:9300",
      "tasks" : {
        "oTUltX4IQMOUUVeiohTt8A:124" : {
          "node" : "oTUltX4IQMOUUVeiohTt8A",
          "id" : 124,
          "type" : "direct",
          "action" : "cluster:monitor/tasks/lists[n]",
          "start_time_in_millis" : 1458585884904,
          "running_time_in_nanos" : 47402,
          "cancellable" : false,
          "parent_task_id" : "oTUltX4IQMOUUVeiohTt8A:123"
        },
        "oTUltX4IQMOUUVeiohTt8A:123" : {
          "node" : "oTUltX4IQMOUUVeiohTt8A",
          "id" : 123,
          "type" : "transport",
          "action" : "cluster:monitor/tasks/lists",
          "start_time_in_millis" : 1458585884904,
          "running_time_in_nanos" : 236042,
          "cancellable" : false
        }
      }
    }
  }
}</pre>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_retrieve_information_from_a_particular_task"></a>Retrieve information from a particular task<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h4>
</div></div></div>
<p>It is also possible to retrieve information for a particular task. The following
example retrieves information about task <code class="literal">oTUltX4IQMOUUVeiohTt8A:124</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks/oTUltX4IQMOUUVeiohTt8A:124</pre>
</div>
<div class="console_widget" data-snippet="snippets/1415.console"></div>
<p>If the task isn’t found, the API returns a 404.</p>
<p>To retrieve all children of a particular task:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks?parent_task_id=oTUltX4IQMOUUVeiohTt8A:123</pre>
</div>
<div class="console_widget" data-snippet="snippets/1416.console"></div>
<p>If the parent isn’t found, the API does not return a 404.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_get_more_information_about_tasks"></a>Get more information about tasks<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h4>
</div></div></div>
<p>You can also use the <code class="literal">detailed</code> request parameter to get more information about
the running tasks. This is useful for telling one task from another but is more
costly to execute. For example, fetching all searches using the <code class="literal">detailed</code>
request parameter:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks?actions=*search&amp;detailed</pre>
</div>
<div class="console_widget" data-snippet="snippets/1417.console"></div>
<p>The API returns the following result:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "nodes" : {
    "oTUltX4IQMOUUVeiohTt8A" : {
      "name" : "H5dfFeA",
      "transport_address" : "127.0.0.1:9300",
      "host" : "127.0.0.1",
      "ip" : "127.0.0.1:9300",
      "tasks" : {
        "oTUltX4IQMOUUVeiohTt8A:464" : {
          "node" : "oTUltX4IQMOUUVeiohTt8A",
          "id" : 464,
          "type" : "transport",
          "action" : "indices:data/read/search",
          "description" : "indices[test], types[test], search_type[QUERY_THEN_FETCH], source[{\"query\":...}]",
          "start_time_in_millis" : 1483478610008,
          "running_time_in_nanos" : 13991383,
          "cancellable" : true
        }
      }
    }
  }
}</pre>
</div>
<p>The new <code class="literal">description</code> field contains human readable text that identifies the
particular request that the task is performing such as identifying the search
request being performed by a search task like the example above. Other kinds of
task have different descriptions, like <a class="xref" href="docs-reindex.html" title="Reindex API"><code class="literal">_reindex</code></a> which
has the search and the destination, or <a class="xref" href="docs-bulk.html" title="Bulk API"><code class="literal">_bulk</code></a> which just has the
number of requests and the destination indices. Many requests will only have an
empty description because more detailed information about the request is not
easily available or particularly helpful in identifying the request.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p><code class="literal">_tasks</code> requests with <code class="literal">detailed</code> may also return a <code class="literal">status</code>. This is a report
of the internal status of the task. As such its format varies from task to task.
While we try to keep the <code class="literal">status</code> for a particular task consistent from version
to version this isn’t always possible because we sometimes change the
implementation. In that case we might remove fields from the <code class="literal">status</code> for a
particular request so any parsing you do of the status might break in minor
releases.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_wait_for_completion"></a>Wait for completion<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The task API can also be used to wait for completion of a particular task. The
following call will block for 10 seconds or until the task with id
<code class="literal">oTUltX4IQMOUUVeiohTt8A:12345</code> is completed.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks/oTUltX4IQMOUUVeiohTt8A:12345?wait_for_completion=true&amp;timeout=10s</pre>
</div>
<div class="console_widget" data-snippet="snippets/1418.console"></div>
<p>You can also wait for all tasks for certain action types to finish. This command
will wait for all <code class="literal">reindex</code> tasks to finish:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks?actions=*reindex&amp;wait_for_completion=true&amp;timeout=10s</pre>
</div>
<div class="console_widget" data-snippet="snippets/1419.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="task-cancellation"></a>Task Cancellation<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h4>
</div></div></div>
<p>If a long-running task supports cancellation, it can be cancelled with the cancel
tasks API. The following example cancels task <code class="literal">oTUltX4IQMOUUVeiohTt8A:12345</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _tasks/oTUltX4IQMOUUVeiohTt8A:12345/_cancel</pre>
</div>
<div class="console_widget" data-snippet="snippets/1420.console"></div>
<p>The task cancellation command supports the same task selection parameters as the
list tasks command, so multiple tasks can be cancelled at the same time. For
example, the following command will cancel all reindex tasks running on the
nodes <code class="literal">nodeId1</code> and <code class="literal">nodeId2</code>.</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST _tasks/_cancel?nodes=nodeId1,nodeId2&amp;actions=*reindex</pre>
</div>
<div class="console_widget" data-snippet="snippets/1421.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_task_grouping"></a>Task Grouping<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The task lists returned by task API commands can be grouped either by nodes
(default) or by parent tasks using the <code class="literal">group_by</code> parameter. The following
command will change the grouping to parent tasks:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks?group_by=parents</pre>
</div>
<div class="console_widget" data-snippet="snippets/1422.console"></div>
<p>The grouping can be disabled by specifying <code class="literal">none</code> as a <code class="literal">group_by</code> parameter:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET _tasks?group_by=none</pre>
</div>
<div class="console_widget" data-snippet="snippets/1423.console"></div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_identifying_running_tasks"></a>Identifying running tasks<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/tasks.asciidoc">edit</a>
</h4>
</div></div></div>
<p>The <code class="literal">X-Opaque-Id</code> header, when provided on the HTTP request header, is going to
be returned as a header in the response as well as in the <code class="literal">headers</code> field for in
the task information. This allows to track certain calls, or associate certain
tasks with the client that started them:</p>
<div class="pre_wrapper lang-sh">
<pre class="programlisting prettyprint lang-sh">curl -i -H "X-Opaque-Id: 123456" "http://localhost:9200/_tasks?group_by=parents"</pre>
</div>
<p>The API returns the following result:</p>
<div class="pre_wrapper lang-js">
<pre class="programlisting prettyprint lang-js">HTTP/1.1 200 OK
X-Opaque-Id: 123456 <a id="CO552-1"></a><i class="conum" data-value="1"></i>
content-type: application/json; charset=UTF-8
content-length: 831

{
  "tasks" : {
    "u5lcZHqcQhu-rUoFaqDphA:45" : {
      "node" : "u5lcZHqcQhu-rUoFaqDphA",
      "id" : 45,
      "type" : "transport",
      "action" : "cluster:monitor/tasks/lists",
      "start_time_in_millis" : 1513823752749,
      "running_time_in_nanos" : 293139,
      "cancellable" : false,
      "headers" : {
        "X-Opaque-Id" : "123456" <a id="CO552-2"></a><i class="conum" data-value="2"></i>
      },
      "children" : [
        {
          "node" : "u5lcZHqcQhu-rUoFaqDphA",
          "id" : 46,
          "type" : "direct",
          "action" : "cluster:monitor/tasks/lists[n]",
          "start_time_in_millis" : 1513823752750,
          "running_time_in_nanos" : 92133,
          "cancellable" : false,
          "parent_task_id" : "u5lcZHqcQhu-rUoFaqDphA:45",
          "headers" : {
            "X-Opaque-Id" : "123456" <a id="CO552-3"></a><i class="conum" data-value="3"></i>
          }
        }
      ]
    }
  }
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO552-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>id as a part of the response header</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO552-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>id for the tasks that was initiated by the REST request</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO552-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>the child task of the task initiated by the REST request</p>
</td>
</tr>
</table>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="cluster-remote-info.html">« Remote cluster info API</a>
</span>
<span class="next">
<a href="voting-config-exclusions.html">Voting configuration exclusions API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>